Windows Plugin Conversion Tutorial
Escape Velocity Nova is designed in such a way that it can be expanded by means of plug-ins. This article is a tutorial for the conversion and installation of Macintosh plugins into Windows plugin format for Windows computers. Conversion the other way cannot be done on the PC due to the resource fork problem, but conversion either way on the Macintosh is simple, and hence does not require a tutorial - simply download the convertor from the Ambrosia Add-on Pages. Warning: This page has lots of images, and may thus take a while to load on slower connections. Quick Steps These are the quick-and-dirty bare bones instructions for expanding Mac archives on the PC. If you want the full version, with images, read on. #Download Stuffit 9 from http://www.stuffit.com #Install #If the archive is .bin or .hqx, right-click and select Stuffit Archive > Expand Here - if it's not either of these, skip this step. #On the .sit file which results, or if the archive starts as .sit or .sitx, right-click and select Stuffit Archive > Expand Mac Archive > MacBinary Fork Encoding #Drag-and-drop the resulting .bin files onto the plugin convertor. #Read the readme to find out where the converted files should go - if it doesn't say, or there's no readme, place them in the Nova Plug-ins folder. #Enjoy Introduction The Macintosh operating system uses two "forks" for storing information in files: the data fork and the resource fork. Since the information stored in Nova plug-ins and data files are all resources, plug-in files use the resource fork only. On the Windows operating system, there is only one fork, the data fork. This means that if a Mac file with a resource fork is placed on a Windows computer, the resource fork will simply be discarded. With the advent of the PC version of EV Nova, Contraband were forced to devise a new method of implementing plugins. This they did, giving it the file extension .rez (Mac plugin files are either .npif or .rsrc, or are quite often extensionless, as file extensions do not matter on the Mac). Furthermore, utilising the MacBinary resource fork conversion already implemented in archive expansion program Stuffit, produced by Allume (then Aladdin Systems), they wrote a plugin conversion program. A tutorial for using this convertor with the then-current version of Stuffit, 7.5, could be found in the Documentation folder for PC Nova 1.0.6. Unfortunately, since the tutorial was written, Stuffit went through two major upgrades, making the tutorial less useful. For a time, it was still appropriate, albeit slightly more complicated, as Stuffit 8 was released without cross-platform expansion options, requiring users to find an old Stuffit 7.5 installer somewhere on the internet. Now, with the release of Stuffit 9, Mac-to-PC plugin conversion is somewhat simpler. However, it is still a little complicated, due to the plethora of archive formats available on the Mac. Getting Started In order to expand Mac plugins on the PC, you first need to download Stuffit version 9. You can get this from http://www.stuffit.com - if the site is opened on a PC, you should be automatically re-directed to the PC section of the page. (If you are not, click here.) To find the free Standard Trial version, click the link marked "Which Stuffit is Right For Me?" as shown in the image below: Then click "Free Download with Standard Edition": You will be asked to fill in a form, then an e-mail will be sent to you enabling you to download the Stuffit trial version. You are encouraged to register the program, but no restrictions will be placed on the program if you do not - instead, the following dialogue box will appear for ten seconds every time you perform an expansion: Once you have Stuffit installed, you must open the Folder Options in Windows and ensure "Hide Extensions of Known File Types" is switched off. To do this, open any Windows Explorer window, and under the "Tools" menu, select "Folder Options...". Click on the "View" tab and uncheck the selected option in the image below: This is vital when working with files of multiple types, and any Windows user worth his salt will aready have it turned off. Expansion There are four main archive types you will usually encounter: .sit, .hqx, .bin and .zip - an image of what the icons look like may be seen below. Note that some icons may differ depending on your file associations. As can be seen from the image, .hqx files and .bin files usually have the same icon - this is one reason why "Hide Extensions of Known File Types" must be turned off. All of the files shown in the image above may be downloaded from the Ambrosia Add-on Pages if you would like to practice the expansion on files which are known to work. Due to an error in the current (as of April 2006) version of Stuffit 9, archives must be expanded slightly differently depending on what type of archive it is. Once you have determined which file type you have, skip to the appropriate section: *.sit(x) *.hqx *.bin *.zip .sit .sit is a file archive format created by Allume (then Aladdin Systems) and up until fairly recently had become a staple for the Macintosh, much as .zip has become a staple for Windows. With the release of Mac OSX and its built-in .zip utility, .zip is becoming a major archive type on the Mac as well, simply for the ease of use. That said, the majority of plugins found on the addon pages are still in .sit format. There is also a variant of .sit called .sea, which stands for 'S'elf 'E'xtracting 'A'rchive - on the Mac, these files can expand themselves without requiring Stuffit to be installed (unlike .sit files). On the PC, however, Stuffit is still required, and the procedure for performing the extraction is the same as for .sit files. Note that the following procedure is required only for the extraction of plugin files - if someone on a Mac sends you a file in a .sit archive which you know to be (for example) an image or a text document, you can simply extract it using normal means. To expand a .sit file, simply right-click on the file to bring up the context menu, and select Stuffit Archive > Expand Mac Archive > MacBinary Fork Encoding. This is shown in the image below. Note that the "Stuffit Archive" submenu is different to the "Stuffit" submenu which may be seen further down the context menu. The result in this case should be a folder containing the files below. Some plugins do not have the files contained in a folder. Most plugins have a readme - usually it is in .txt or .rtf format, but this particular plugin has a .html readme contained in a subfolder. Sometimes the Stuffit MacBinary conversion can be a little overzealous, and may render music files and readmes as .bin files. In these cases, "Expand Here" should be selected in order to retrieve these files, as well as using "MacBinary Fork Encoding" to produce the plugins. (Alternately, manually changing the file extension to the correct format usually works in this case, as the files have no resource forks and were thus not changed by the MacBinary enconding.) You will see that each plug-in file is now in the form of a .bin file. Note that though they claim to be Stuffit archives, they are not - they are Mac'Bin'ary files. Attempting to expand them using Stuffit will not produce a desireable result. You will also see a file named .DS_Store - this file may be deleted, as it is a Mac-only file. If the plugin had a custom icon when it was originally made on the Mac, a file named _Icon will appear which may also be deleted (although the icon itself will not appear). The .bin files may now be converted. Skip to the conversion section below. Note that if the file is extracted incorrectly (for example, by selecting "Expand Here") then the result will be the files shown below. Since plug-in information is stored in the resource fork, which cannot exist on the PC, the resulting files have a size of zero bytes. If you receive a dialogue box reading "Engine Error (3): The system cannot find the path specified" when you try to expand a .sit archive, the solution is to right-click the .sit archive in question, and select "View with Stuffit". When Stuffit opens, right-click on the file named "Icon" and select "Delete". Then you should be able to expand the .sit file as with the procedure above. Occasionally, you will see a file with format .sitx as shown below - this is a relatively new file format, and is not seen as often as the other types. Simply extract using the same method as for .sit files above. .hqx .hqx files are almost always in the form of .sit.hqx - that is, a .sit archive contained within a .hqx archive. Strictly speaking, .hqx is not an archive but actually a form of encoding, which is why it makes the file size larger when it is used. In the nineties, it was required to encode a file correctly in order to successfully upload it to the internet from a Mac - failure to do this would result in a gibberish file. Today, it is no longer required, but people continue encoding from force of habit. .hqx encoding of plug-ins is gradually being phased out due to the efforts of plugin developers such as Zacha Pedro, but they can still be found on the addon pages. Due to a bug in Stuffit 9, .hqx files must be expanded by using the "Expand Here" option as shown in the image below. If you use the cross-platform expansion options, you will either get a zero byte size file with the name of the folder in which you did the expansion, or you will get an error dialogue box. The correct result of the expansion is shown below - expand the resulting .sit archive using the method above. Return to .sit instructions. .hqx files can also be expanded using WinZip, but this is not advised, as it has been known to cause problems on occasion. .bin Like .hqx, .bin is an encoding format - specifically, it's short for Mac'Bin'ary, that wonderful format which is the desired end result of this expansion section. The .bin "archive" is usually a MacBinary-encoded .sit archive - this is different to the MacBinary-encoded plugin file which we put in the plugin convertor, and it is important to realise this difference. Typically, a .bin encoded archive will be called .sit.bin. To tell the difference between a .bin encoded plugin file and a .bin encoded archive, a simple rule of thumb is this: if you downloaded it from the Addon pages, it's an archive, but if you got it as the output from an archive expansion, it's a file. Another test is to simply expand the file with Stuffit - if the result is a zero-size file, then it was a .bin encoded plugin file, and should not have been expanded. Do not put .bin encoded archives through the plugin convertor, as they will cause it to crash. To expand a .bin encoded archive, either "Expand Here" or "MacBinary Fork Encoding" may be used - it does not matter which, as both methods work. The latter has been known to generate an error message or two, but the expansion proceeds nonetheless. The result of the expansion is shown below - expand the resulting .sit archive using the method above. Return to .sit instructions. .zip Just to add confusion, there are three kinds of .zip files. Strictly speaking, there's only one kind, but depending on how the compression was done, the results can be very different, so there are effectively three kinds. All three types are simply expanded using WinZip, WinRar, WinAce, or other Windows archive utility of choice - the image below shows expansion using the WinRar context menu expansion option. The three kinds are as follows: PC .zip archives, Mac .zip archives which have been properly compressed, and Mac .zip archives which have not been properly compressed. All three kinds have the same icon in Windows - which is logical, as strictly speaking they're all the same file format. The first kind is the PC .zip archive. When extracted using WinZip, the result is one or more PC .rez plugin files - the result of the above expansion may be seen in the image below. Simply skip to the Installation section for instructions on what to do next. The remaining two kinds are the Mac .zip archives. Much like Windows XP, the Macintosh operating system version ten (Mac OSX) comes with a .zip compression utility installed. Due to the resource fork problem, Mac users must pre-encode their plugin files in MacBinary format when archiving as a .zip file. However, the OSX utility does not do this, so if a file is compressed using this utility, it cannot be correctly expanded on the PC. The only way to find if it can be correctly expanded is to simply do the expansion. For the record, the file on the left has been compressed correctly, while the file on the right has not. If the file was compressed correctly, something like the following files will result. The .bin files need to be converted. Skip to the conversion section below. If the file was not compressed correctly, the following files will result. The only course of action is to either contact the plugin creator and ask them to re-compress the file, or to (nicely) ask some willing soul who is on a Mac to do it. Conversion To convert .bin files in to .rez plugin files, simply drag-and-drop them on to the plugin convertor found in the Nova folder. As can be seen below, it's called "Convert Plug-ins.exe". A window similar to the following will flash up reasonably fast, and then vanish, and the converted files will appear in the same directory as the files you were converting. In this case, the results are shown below. If your plugin convertor produces a resource.map file (highlighted in the image) then delete it, as it causes several problems when Nova tries to run. Do not drop readmes, music files or image files onto the convertor, and if an archive is dragged onto the convertor, it will crash. If it does not already have the correct extension, any music file should manually have a .mp3 extension added to the end (the file should already be in the correct format, but they must have the extension for Nova to recognise them). Note that several files may be converted at once by dragging all of the files at the same time, but if a folder is dropped onto the convertor, it will not work. Once the conversion is done, continue to the Installation section below. Installation Typically, the readme should contain installation instructions. Most plugins are simply placed in the Nova Plug-ins folder, but some large plugins, especially Total Conversions are designed to replace the Nova Data files. In this case, the existing Nova Files folder should be re-named (say, to "Nova Files Original") and the folder containing the TC files be named "Nova Files". Note that plugin files must be directly within the relevant folders - if they are inside a folder which is itself within the Nova Plug-ins folder, then the game will not recognise them. Also note that many plugins will conflict with each other - usually they will say in the Readme which plugins are compatible, if any (or which ones are not). Plugins load in the following order: files in the Nova Files folder, in alphabetical order, then files in the Nova Plug-ins folder, in alphabetical order. If two plugins share a resource, then the plugin that loads last will take precedence, and only that resource will appear in the game. If you know what you are doing, you could potentially run the game with plugin clashes, but be warned that results can be unpredictible, especially in the more complicated plugins. Final Words Some plugins cannot be converted on the PC, regardless of what is done, simply because they were incorrectly compressed on the Mac. In these cases, the only thing which can be done is to contact the plugin maker, or else find a willing Mac user who will expand and re-compress the file for you. If you simply cannot get the context menu to behave properly, then you can force Stuffit to always perform the cross-platform expansion by opening the options and setting the Cross-Platform settings as shown below. Note that this will render you incapable of extracting .hqx archives. Category:Miscellaneous